home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat2 / sigaction.0 < prev    next >
Text File  |  1996-09-01  |  11KB  |  199 lines
  1.  
  2. SIGACTION(2)               UNIX Programmer's Manual               SIGACTION(2)
  3.  
  4. NNAAMMEE
  5.      ssiiggaaccttiioonn - software signal facilities
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ssiiggnnaall..hh>>
  9.      struct sigaction {
  10.              void     (*sa_handler)();
  11.              sigset_t sa_mask;
  12.              int      sa_flags;
  13.      };
  14.  
  15.      _i_n_t
  16.      ssiiggaaccttiioonn(_i_n_t _s_i_g, _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n _*_a_c_t, _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n _*_o_a_c_t)
  17.  
  18. DDEESSCCRRIIPPTTIIOONN
  19.      The system defines a set of signals that may be delivered to a process.
  20.      Signal delivery resembles the occurrence of a hardware interrupt: the
  21.      signal is blocked from further occurrence, the current process context is
  22.      saved, and a new one is built.  A process may specify a _h_a_n_d_l_e_r to which
  23.      a signal is delivered, or specify that a signal is to be _i_g_n_o_r_e_d. A pro-
  24.      cess may also specify that a default action is to be taken by the system
  25.      when a signal occurs.  A signal may also be _b_l_o_c_k_e_d, in which case its
  26.      delivery is postponed until it is _u_n_b_l_o_c_k_e_d. The action to be taken on
  27.      delivery is determined at the time of delivery.  Normally, signal han-
  28.      dlers execute on the current stack of the process.  This may be changed,
  29.      on a per-handler basis, so that signals are taken on a special _s_i_g_n_a_l
  30.      _s_t_a_c_k.
  31.  
  32.      Signal routines execute with the signal that caused their invocation
  33.      _b_l_o_c_k_e_d, but other signals may yet occur.  A global _s_i_g_n_a_l _m_a_s_k defines
  34.      the set of signals currently blocked from delivery to a process.  The
  35.      signal mask for a process is initialized from that of its parent (normal-
  36.      ly empty).  It may be changed with a sigprocmask(2) call, or when a sig-
  37.      nal is delivered to the process.
  38.  
  39.      When a signal condition arises for a process, the signal is added to a
  40.      set of signals pending for the process.  If the signal is not currently
  41.      _b_l_o_c_k_e_d by the process then it is delivered to the process.  Signals may
  42.      be delivered any time a process enters the operating system (e.g., during
  43.      a system call, page fault or trap, or clock interrupt).  If multiple sig-
  44.      nals are ready to be delivered at the same time, any signals that could
  45.      be caused by traps are delivered first.  Additional signals may be pro-
  46.      cessed at the same time, with each appearing to interrupt the handlers
  47.      for the previous signals before their first instructions.  The set of
  48.      pending signals is returned by the sigpending(2) function.  When a caught
  49.      signal is delivered, the current state of the process is saved, a new
  50.      signal mask is calculated (as described below), and the signal handler is
  51.      invoked.  The call to the handler is arranged so that if the signal han-
  52.      dling routine returns normally the process will resume execution in the
  53.      context from before the signal's delivery.  If the process wishes to re-
  54.      sume in a different context, then it must arrange to restore the previous
  55.      context itself.
  56.  
  57.      When a signal is delivered to a process a new signal mask is installed
  58.      for the duration of the process' signal handler (or until a sigprocmask
  59.      call is made).  This mask is formed by taking the union of the current
  60.      signal mask set, the signal to be delivered, and the signal mask associ-
  61.      ated with the handler to be invoked.
  62.  
  63.      SSiiggaaccttiioonn() assigns an action for a specific signal.  If _a_c_t is non-zero,
  64.      it specifies an action (SIG_DFL, SIG_IGN, or a handler routine) and mask
  65.      to be used when delivering the specified signal.  If _o_a_c_t is non-zero,
  66.      the previous handling information for the signal is returned to the user.
  67.  
  68.      Once a signal handler is installed, it remains installed until another
  69.      ssiiggaaccttiioonn() call is made, or an execve(2) is performed.  A signal-
  70.      specific default action may be reset by setting _s_a___h_a_n_d_l_e_r to SIG_DFL.
  71.      The defaults are process termination, possibly with core dump; no action;
  72.      stopping the process; or continuing the process.  See the signal list be-
  73.      low for each signal's default action.  If _s_a___h_a_n_d_l_e_r is SIG_DFL, the de-
  74.      fault action for the signal is to discard the signal, and if a signal is
  75.      pending, the pending signal is discarded even if the signal is masked.
  76.      If _s_a___h_a_n_d_l_e_r is set to SIG_IGN current and pending instances of the sig-
  77.      nal are ignored and discarded.
  78.  
  79.      Options may be specified by setting _s_a___f_l_a_g_s. If the SA_NOCLDSTOP bit is
  80.      set when installing a catching function for the SIGCHLD signal, the
  81.      SIGCHLD signal will be generated only when a child process exits, not
  82.      when a child process stops.  Further, if the SA_ONSTACK bit is set in
  83.      _s_a___f_l_a_g_s, the system will deliver the signal to the process on a _s_i_g_n_a_l
  84.      _s_t_a_c_k, specified with sigstack(2).
  85.  
  86.      If a signal is caught during the system calls listed below, the call may
  87.      be forced to terminate with the error EINTR, the call may return with a
  88.      data transfer shorter than requested, or the call may be restarted.
  89.      Restart of pending calls is requested by setting the SA_RESTART bit in
  90.      _s_a___f_l_a_g_s. The affected system calls include open(2),  read(2),  write(2),
  91.       sendto(2),  recvfrom(2),  sendmsg(2) and recvmsg(2) on a communications
  92.      channel or a slow device (such as a terminal, but not a regular file) and
  93.      during a wait(2) or ioctl(2).  However, calls that have already committed
  94.      are not restarted, but instead return a partial success (for example, a
  95.      short read count).
  96.  
  97.      After a fork(2) or vfork(2) all signals, the signal mask, the signal
  98.      stack, and the restart/interrupt flags are inherited by the child.
  99.  
  100.      Execve(2) reinstates the default action for all signals which were caught
  101.      and resets all signals to be caught on the user stack.  Ignored signals
  102.      remain ignored; the signal mask remains the same; signals that restart
  103.      pending system calls continue to do so.
  104.  
  105.      The following is a list of all signals with names as in the include file
  106.      <_s_i_g_n_a_l_._h>:
  107.  
  108.      NNAAMMEE            DDeeffaauulltt AAccttiioonn          DDeessccrriippttiioonn
  109.      SIGHUP          terminate process       terminal line hangup
  110.      SIGINT          terminate process       interrupt program
  111.      SIGQUIT         create core image       quit program
  112.      SIGILL          create core image       illegal instruction
  113.      SIGTRAP         create core image       trace trap
  114.      SIGABRT         create core image       abort(2) call (formerly SIGIOT)
  115.      SIGEMT          create core image       emulate instruction executed
  116.      SIGFPE          create core image       floating-point exception
  117.      SIGKILL         terminate process       kill program
  118.      SIGBUS          create core image       bus error
  119.      SIGSEGV         create core image       segmentation violation
  120.      SIGSYS          create core image       system call given invalid
  121.                                              argument
  122.      SIGPIPE         terminate process       write on a pipe with no reader
  123.      SIGALRM         terminate process       real-time timer expired
  124.      SIGTERM         terminate process       software termination signal
  125.      SIGURG          discard signal          urgent condition present on
  126.                                              socket
  127.      SIGSTOP         stop process            stop (cannot be caught or
  128.                                              ignored)
  129.      SIGTSTP         stop process            stop signal generated from
  130.  
  131.  
  132.                                              keyboard
  133.      SIGCONT         discard signal          continue after stop
  134.      SIGCHLD         discard signal          child status has changed
  135.      SIGTTIN         stop process            background read attempted from
  136.                                              control terminal
  137.      SIGTTOU         stop process            background write attempted to
  138.                                              control terminal
  139.      SIGIO           discard signal          I/O is possible on a descriptor
  140.                                              (see fcntl(2))
  141.      SIGXCPU         terminate process       cpu time limit exceeded (see
  142.                                              setrlimit(2))
  143.      SIGXFSZ         terminate process       file size limit exceeded (see
  144.                                              setrlimit(2))
  145.      SIGVTALRM       terminate process       virtual time alarm (see
  146.                                              setitimer(2))
  147.      SIGPROF         terminate process       profiling timer alarm (see
  148.                                              setitimer(2))
  149.      SIGWINCH        discard signal          Window size change
  150.      SIGINFO         discard signal          status request from keyboard
  151.      SIGUSR1         terminate process       User defined signal 1
  152.      SIGUSR2         terminate process       User defined signal 2
  153.  
  154. NNOOTTEE
  155.      The mask specified in _a_c_t is not allowed to block SIGKILL or SIGSTOP.
  156.      This is done silently by the system.
  157.  
  158. RREETTUURRNN VVAALLUUEESS
  159.      A 0 value indicated that the call succeeded.  A -1 return value indicates
  160.      an error occurred and _e_r_r_n_o is set to indicated the reason.
  161.  
  162. EEXXAAMMPPLLEE
  163.      The handler routine can be declared:
  164.  
  165.            void handler(sig, code, scp)
  166.            int sig, code;
  167.            struct sigcontext *scp;
  168.  
  169.      Here _s_i_g is the signal number, into which the hardware faults and traps
  170.      are mapped.  _C_o_d_e is a parameter that is either a constant or the code
  171.      provided by the hardware.  _S_c_p is a pointer to the _s_i_g_c_o_n_t_e_x_t structure
  172.      (defined in <_s_i_g_n_a_l_._h>), used to restore the context from before the sig-
  173.      nal.
  174.  
  175. EERRRROORRSS
  176.      SSiiggaaccttiioonn() will fail and no new signal handler will be installed if one
  177.      of the following occurs:
  178.  
  179.      [EFAULT]      Either _a_c_t or _o_a_c_t points to memory that is not a valid
  180.                    part of the process address space.
  181.  
  182.      [EINVAL]      _S_i_g is not a valid signal number.
  183.  
  184.      [EINVAL]      An attempt is made to ignore or supply a handler for
  185.                    SIGKILL or SIGSTOP.
  186.  
  187. SSTTAANNDDAARRDDSS
  188.      The ssiiggaaccttiioonn function is defined by IEEE Std1003.1-1988 (``POSIX''). The
  189.      SA_ONSTACK and SA_RESTART flags are Berkeley extensions, as are the sig-
  190.      nals, SIGTRAP, SIGEMT, SIGBUS, SIGSYS, SIGURG, SIGIO, SIGXCPU, SIGXFSZ,
  191.      SIGVTALRM, SIGPROF, SIGWINCH, and SIGINFO. Those signals are available on
  192.      most BSD-derived systems.
  193.  
  194. SSEEEE AALLSSOO
  195.      kill(1),  ptrace(2),  kill(2),  sigaction(2),  sigprocmask(2),
  196.      sigsuspend(2),  sigblock(2),  sigsetmask(2),  sigpause(2),  sigstack(2),
  197.      sigvec(3),  setjmp(3),  siginterrupt(3),  sigsetops(3),  tty(4)
  198.  
  199.